这个课程不是Codevolution的，而是Ali Alaa这个人的。

Installation

参考：https://tanstack.com/router/latest/docs/framework/react/installation/manual#using-file-based-route-generation

创建项目：pnpm create vite。

安装依赖：

xxxxxxxxxx
2
1
pnpm add @tanstack/react-router @tanstack/react-router-devtools
2
pnpm add -D @tanstack/router-plugin

配置Vite插件：

安装tailwind：pnpm add tailwindcss @tailwindcss/vite

配置tailwind：

Code Based Router

TanStack Router 的 code-based router（代码式路由）结构其实非常直白，就是手动用 createRootRoute + createRoute 构建一棵路由树，最后通过 createRouter 创建路由器实例。

官方其实强烈推荐使用 file-based routing（文件系统路由），但如果你就是想用纯代码方式（比如小项目、动态路由特别多、或不喜欢插件生成代码），就可以使用Code based router。

两种方式虽然实现方式不同，但最终形成的routeTree结构是一样的，都要有一个rootRoute。

xxxxxxxxxx
9
1
rootRoute
2
├── indexRoute          (/)
3
├── aboutRoute          (/about)
4
├── postsRoute          (/posts)
5
│   └── postDetailRoute (/posts/$postId)
6
├── _auth (layout)      (不占路径，只是布局)
7
│   └── dashboard       (/_auth/dashboard → /dashboard)
8
└── login               (/login)
9
    └── etc...

二者不同：

参考文档：https://tanstack.com/router/latest/docs/framework/react/routing/code-based-routing

xxxxxxxxxx
62
1
// main.tsx
2
​
3
import { StrictMode } from 'react'
4
import { createRoot } from 'react-dom/client'
5
import './index.css'
6
import {
7
  createRootRoute,
8
  createRoute,
9
  Outlet,
10
  RouterProvider,
11
  createRouter,
12
} from "@tanstack/react-router";
13
import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
14
​
15
// 创建路由
16
const rootRoute = createRootRoute({
17
  component: () => (
18
    <div className="bg-green-500 p-2">
19
      <h1 className="text-2xl font-bold">Root Route</h1>
20
      <Outlet />
21
      <TanStackRouterDevtools />
22
    </div>
23
  ),
24
});
25
​
26
const indexRoute = createRoute({
27
  getParentRoute: () => rootRoute,
28
  path: "/",
29
  component: function Index() {
30
    return (
31
      <div className="p-2 bg-violet-500">
32
        <h3 className="text-xl font-bold">Home</h3>
33
      </div>
34
    );
35
  },
36
});
37
​
38
const aboutRoute = createRoute({
39
  getParentRoute: () => rootRoute,
40
  path: "/about",
41
  component: function About() {
42
    return (
43
      <div className="p-2 bg-pink-500">
44
        <h3 className="text-xl font-bold">About</h3>
45
      </div>
46
    );
47
  },
48
});
49
​
50
// 手动构建路由树
51
const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]);
52
​
53
// Set up a Router instance
54
const router = createRouter({
55
  routeTree,
56
});
57
​
58
createRoot(document.getElementById("root")!).render(
59
  <StrictMode>
60
    <RouterProvider router={router} />
61
  </StrictMode>
62
);

可以看到，路由跳转正常，使用devtools可以帮助我们跳转路由，并且展示路由树。

除了rootRoute之外，都使用createRoute方法来创建，必须设置getParentRoute参数。

Navigation Links

使用Link组件来进行路由跳转。

当前路由菜单高亮有多种方法来做，因为当前路由会添加一个active的类名，所以这里直接使用tailwind来做了。

路由跳转正常。

File Based Router

核心工作原理：

你按照特定命名约定写文件 → 构建工具插件（比如说vite插件）（或 CLI）扫描目录 → 自动生成一份类型安全的 routeTree.gen.ts → 你在入口只引入这一行就拥有完整路由树。

我们只需要做第一步：按照约定写文件。

例子：

xxxxxxxxxx
17
1
src/
2
  routes/                     ← 约定目录（可改名）
3
  ├── __root.tsx              # 根路由（通常放全局 layout）
4
  ├── index.tsx               # → 对应路径: /
5
  ├── about.tsx               # → /about
6
  ├── dashboard/
7
  │   ├── index.tsx           # → /dashboard
8
  │   ├── route.tsx           # 显式路由文件（可选）
9
  │   ├── _layout.tsx         # → 布局路由（渲染 <Outlet />）
10
  │   ├── users/
11
  │   │   └── $userId.tsx     # → /dashboard/users/:userId
12
  │   └── settings/
13
  │       ├── index.tsx       # → /dashboard/settings
14
  │       └── .tsx            # 故意忽略（文件名前面加 . 或 _ 开头通常忽略）
15
  └── posts/
16
      ├── $slug.tsx           # → /posts/:slug
17
      └── $                       # 贪婪匹配（splat） → /posts/后面全部

常用的几种特殊文件名约定：

基本使用

在src下插件routes文件夹，然后创建文件，@tanstack/router的vite插件，会帮助我们自动生成范例代码，我们只需要进行相应修改即可，太方便了：

下一步就简单了，将之前定义好的组件内容粘贴过来即可，我粘贴root过来示范：

xxxxxxxxxx
29
1
// src/routes/__root.tsx
2
​
3
import * as React from "react";
4
import { Link, Outlet, createRootRoute } from "@tanstack/react-router";
5
import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
6
​
7
export const Route = createRootRoute({
8
  component: RootComponent,
9
});
10
​
11
function RootComponent() {
12
  return (
13
    <React.Fragment>
14
      <div className="bg-green-500 p-2">
15
        <h1 className="text-2xl font-bold">Root Route</h1>
16
        <div className="p-2 flex gap-2 mb-4 bg-teal-500">
17
          <Link to="/" className="[&.active]:font-bold">
18
            Home
19
          </Link>
20
          <Link to="/about" className="[&.active]:font-bold">
21
            About
22
          </Link>
23
        </div>
24
        <Outlet />
25
        <TanStackRouterDevtools />
26
      </div>
27
    </React.Fragment>
28
  );
29
}

在ruotes里面创建了文件之后，在src文件夹中会自动生成routeTree.gen.ts文件，这是插件帮助我们自动生成的，里面有一个routeTree暴露出来。

然后在main.tsx里面引入routeTree来使用。

可以看到，路由正常。

Nesting Routes

只要文件放在某个目录下，默认就会成为该目录对应路由的子路由。这是tanstack/router的基本约定。

这节课讨论两种情况。

1、index.tsx和route.tsx的区别

index.tsx

当一个文件夹里面是index.tsx文件时，表示该目录的「默认/索引」页面，目录路径精确匹配时才会显示这个页面。

可以看到，生成的routeTree里面，有三个路由地址。

route.tsx

表示该目录的「主路由定义文件」（通常用来做 layout），非常适合做父级，能自然包含所有子路由。

要结合<Outlet />一起使用。

可以看到，生成的routeTree里面，有两个路由地址。

xxxxxxxxxx
5
1
# 两种等价的布局写法（社区两种最常见风格）
2
dashboard/
3
├── route.tsx           # 风格1：简洁、直观
4
# 或
5
├── _layout.tsx         # 风格2：更明确是布局（类似 Next.js 早期）

快速决策表（开发中最常用的选择指南）

2、文件名或目录名后面加_

Route segments with the _ suffix exclude the route from being nested under any parent routes.

表示断开嵌套关系。注意：不是路由地址断开嵌套，而是页面内容断开嵌套。

文件名或目录名后面的下划线是一个“解耦”工具。它允许你保持 /parent/child 这样的优雅 URL 结构，同时又能在 UI 层面灵活地摆脱父级组件（Layout）的束缚。

注意看，路由地址在settings之间改变，但是settings/login页面的内容就不会被settings文件夹里面的任何内容影响。

xxxxxxxxxx
6
1
想让子页面有父布局？     →  在父目录放 _layout.tsx（最推荐）
2
父路由自己也有内容？       →  放 index.tsx 或者 route.tsx
3
不想被父布局包？           →  文件名/目录名前面加 _ （下划线断开）
4
想要分组但不要路径前缀？   →  用括号 (group) 做分组目录
5
想要动态参数？             →  $param.tsx
6
想要全部剩余路径？         →  $xxx.tsx 或者单纯一个 $ 文件

解决 TanStack Router 所有“隐式 any”问题的终极方案。你需要确保在项目的入口文件（如 main.tsx 或 App.tsx）中添加了类型声明。加了这段声明之后，可以省很多心。

xxxxxxxxxx
9
1
// 在创建 router 实例的地方
2
const router = createRouter({ routeTree })
3
​
4
// 必须添加这段声明，TS 才能全局感知每个路由的 Search Params 类型
5
declare module '@tanstack/react-router' {
6
interface Register {
7
 router: typeof router
8
}
9
}

Pathless Layouts

在 TanStack Router 中，前缀下划线（例如 _layout.tsx 或 _auth/）被称为 Pathless Route（无路径路由）。

它的核心作用是：为了逻辑分组或 UI 嵌套，但不在 URL 路径中显示。

1. 核心定义

当你给文件夹或文件加上 _ 前缀时，你是在告诉路由器：

• UI 层面：我想通过这个文件创建一个布局（Layout）或共享一个逻辑（如权限检查）。
• URL 层面：请忽略这个名字，不要把它加到浏览器的地址栏里。

2. 实际案例对比

假设你的需求是：/login 和 /register 页面需要共享一个蓝色的背景和公司的 Logo。

❌ 不使用前缀的情况

如果你的结构是：

• auth/

  • login.tsx
  • register.tsx

生成的 URL：/auth/login 和 /auth/register。

✅ 使用前缀 _ 的情况

如果你的结构是：

• _auth.tsx (布局组件，包含蓝色背景和 Logo，需要加<Outlet />)

• _auth/

  • login.tsx
  • register.tsx

生成的 URL：/login 和 /register。 虽然 URL 里没有 auth，但这两个页面都会自动嵌套在 _auth.tsx 的 <Outlet /> 中。

3. 三大使用场景

① 视觉布局分组 (Visual Grouping)

这是最常见的用法。你可能希望“营销页”用一套导航栏，“管理后台”用另一套导航栏，但 URL 都想从根目录开始（如 /home 和 /dashboard）。

• _marketing/home.tsx -> /home
• _admin/dashboard.tsx -> /dashboard

② 逻辑与权限控制 (Auth/Logic Wrappers)

你可以创建一个 _authenticated.tsx 文件，在里面编写重定向逻辑：如果用户未登录，则跳转到登录页。所有放在 _authenticated/ 文件夹下的路由都会自动受到这个逻辑的保护，而 URL 中不会多出 /authenticated/ 这一层。

③ 纯粹的文件组织

当你的项目非常大时，你可能只想把相关的页面放在一起管理，但不希望改变现有的 SEO 友好的 URL 结构。

注意看，路由地址是很简洁的，同时也有_auth.tsx文件的内容。

pathless route不只是可以省略一段url path，更重要的是共享一段逻辑或样式。

如果单纯的只是想要省略一段url path，那么可以使用(folder)，小括号来实现。

Ignored Folders

- Prefix

有时候，我们想就近编写一些组件，而不是都放到src/components这个文件夹里面。但是一个文件夹就是一个路由地址，该怎么办才能让tanstack/router忽略这个文件夹呢？

可以在文件夹或者文件名前面加上-，这样就会排除出路由树了。

Files and folders with the - prefix are excluded from the route tree. They will not be added to the routeTree.gen.ts file and can be used to colocate logic in route folders.

可以看到，Nav组件正常使用了。

(folder) folder name pattern

A folder that matches this pattern is treated as a route group, preventing the folder from being included in the route's URL path.

路由分组。它纯粹是为了组织文件，完全不影响路由的层级。

核心作用

• 不影响 URL 路径：括号里的名字不会出现在地址栏。
• 不增加 UI 布局层级：这是它与 _layout（前缀下划线）最大的不同。它不会寻找一个所谓的“布局文件”来嵌套子页面，它只是一个逻辑上的文件夹。

Flat Routes

在 TanStack Router 中，Flat Routes (扁平路由) 是一种通过文件名中的特殊分隔符（如 .）来表达路由层级，而不是依赖物理文件夹层级的方案。

它是 TanStack Router v1.0 之后的推荐趋势。

1. 什么是 Flat Routes？

在 Flat Routes 模式下，你不需要一层套一层的文件夹。你直接在 routes/ 根目录下创建文件，用点 . 来代表路径分隔符。

对比示例：

• 文件夹模式 (Folder-based):

  • routes/dashboard/index.tsx
  • routes/dashboard/settings.tsx
  • routes/dashboard/profile.tsx

• Flat Routes 模式:

  • routes/dashboard.index.tsx
  • routes/dashboard.settings.tsx
  • routes/dashboard.profile.tsx

2. 扁平路由用的多吗？

非常多，甚至正在成为主流。

TanStack Router 的官方 CLI 工具和示例代码现在默认倾向于使用这种扁平化结构。原因在于：

1. 文件查找极快：所有路由文件都在一个列表里，一眼就能看到项目有多少个页面，不需要反复展开/折叠多层文件夹。
2. 避免“Index 泥潭”：在文件夹模式下，你会有一堆名为 index.tsx 的文件，在编辑器标签页里很难分辨。扁平模式下，文件名就是完整路径（如 dashboard.settings.tsx），非常清晰。

3. Flat Routes vs. 文件夹模式：深度对比

4. 哪个更好一些？

这取决于你的代码组织习惯：

选 Flat Routes (推荐) 如果：

• 你讨厌在 VS Code 里点开五层文件夹才找到文件。
• 你希望通过文件名就能定位路由逻辑。
• 你遵循“路由文件只负责逻辑， UI 组件放在外部 components/ 文件夹”的规范。

选 文件夹模式 如果：

• 你喜欢“就近原则”（Colocation），即把当前页面专用的 Button.tsx、styles.css 直接丢在对应的路由文件夹里。
• 你的项目层级极深（例如超过 5 层），文件名可能会变得非常长（如 admin.settings.users.profile.details.tsx）。

5. 混合模式 (Hybrid)

实际上，TanStack Router 支持混合使用。你可以在 routes/ 下用扁平化命名处理简单路由，对于复杂的模块（比如有大量私有组件的 Dashboard），再开一个文件夹。

总结建议

对于新项目，强烈建议优先使用 Flat Routes。它配合你之前问的 _（前缀/后缀）能组合出非常灵活的方案：

• _auth.login.tsx (Pathless 布局 + 扁平路径)
• dashboard_.billing.tsx (打破嵌套的扁平路径)

Dynamic Path Segments

Route segments with the $ token are parameterized and will extract the value from the URL pathname as a route param.

在 TanStack Router 中，Dynamic Path Segments（动态路径段） 是处理 URL 变量（如 ID、用户名等）的核心机制。它允许你通过定义通配符来匹配不同的路径。

在文件路由中，动态段的主要标志是 $ 符号。

1. 基础语法：使用 $

当你希望 URL 中的某一部分是变动的时候，就在文件名或文件夹名中使用 $。

• 文件结构：routes/posts.$postId.tsx
• 匹配 URL：/posts/1、/posts/abc、/posts/hello-world
• 解析结果：postId 的值分别为 1、abc、hello-world。

2. 在代码中获取参数

定义了动态路由后，你需要通过 TanStack Router 提供的 Hook useParams 来获取具体的值。

xxxxxxxxxx
12
1
import { createFileRoute } from '@tanstack/react-router'
2
​
3
export const Route = createFileRoute('/posts/$postId')({
4
  component: PostComponent,
5
})
6
​
7
function PostComponent() {
8
  // 获取动态参数
9
  const { postId } = Route.useParams()
10
  
11
  return <div>当前浏览的帖子 ID 是: {postId}</div>
12
}

3. 三种常见的动态段类型

① 单个段 (Single Segment)

• 文件名：users.$userId.tsx
• 匹配：/users/123
• 说明：只匹配路径中的这一层。

② 多个段 (Multiple Segments)

• 文件名：blog.$categoryId.$postId.tsx
• 匹配：/blog/tech/how-to-code
• 说明：你可以同时获取 categoryId 和 postId。

4. 动态段与类型安全（TanStack Router 的杀手锏）

与其他路由库（如 React Router）不同，TanStack Router 的动态段是全自动类型化的。

• 如果你在文件名里写了 $postId，你在代码里调用 useParams() 时，编辑器会自动补全 postId。
• 如果你尝试访问一个不存在的参数（比如 data.id），TypeScript 会直接报错。

5. 进阶：在 Loader 中使用动态段

动态段最常用的场景是在 loader 中获取数据。例如根据 ID 从 API 请求数据：

xxxxxxxxxx
3
1
export const Route = createFileRoute('/posts/$postId')({
2
  loader: ({ params }) => fetchPost(params.postId), // params 自动包含 postId
3
})

6. Link标签使用params参数传参

Link的to参数，还是写成定义的路由地址那样/posts/$postId，使用params来传递参数。

xxxxxxxxxx
2
1
<Link to="/posts/$slug" params={{ postId: 1 }}>
2
</Link>

上面这种方式主要是为了类型安全，也可以直接在to参数上拼接来传参。

Catch-All Routes

在 TanStack Router 中，Catch-All Routes（全匹配路由 / 通配符路由） 用于匹配 URL 中剩余的所有路径部分。当你无法预知路径有多少层级，或者想要捕获所有错误的路径时，这个功能非常有用。

在文件路由中，Catch-All 的核心标志是单个美金符号 $（不带任何名称）。

1. 语法与命名规则

在扁平路由（Flat Routes）或文件夹路由中，你只需要将文件命名为 $.tsx。

• 文件路径：routes/docs.$.tsx

• 匹配情况：

  • /docs/intro (匹配)
  • /docs/setup/installation/windows (匹配)
  • /docs (不一定匹配，通常需要 docs.index.tsx 处理根路径)

2. 如何获取匹配到的路径值？

由于 Catch-All 匹配的是“剩余的所有部分”，TanStack Router 会将匹配到的路径以字符串的形式存储在 params 中，属性名固定为 _ (下划线)。

xxxxxxxxxx
18
1
import { createFileRoute } from '@tanstack/react-router'
2
​
3
export const Route = createFileRoute('/docs/$')({
4
  component: DocComponent,
5
})
6
​
7
function DocComponent() {
8
  // 注意：属性名是下划线 "_"
9
  const { _ } = Route.useParams()
10
  
11
  return (
12
    <div>
13
      <h1>文档查看器</h1>
14
      <p>当前匹配的完整路径是: {_}</p> 
15
      {/* 如果访问 /docs/a/b/c，则 _ 的值是 "a/b/c" */}
16
    </div>
17
  )
18
}

3. Catch-All 的常见用途

① 404 页面（NotFound）

这是最常见的用途。在 routes/ 根目录下创建一个 $.tsx，它会捕获所有无法匹配到已有路由的请求。

• routes/$.tsx -> 匹配任何未定义的 URL，展示 404 UI。

② 层次结构不固定的文件管理器

如果你在做一个类似百度网盘或 GitHub 的文件浏览器，路径深度是动态的：

• routes/storage/$.tsx
• URL: /storage/work/projects/2024/plan.pdf
• params._ 的值就是 work/projects/2024/plan.pdf。你可以根据这个字符串去后端查询文件。

4. 优先级与匹配规则

TanStack Router 的路由匹配遵循 “最具体优先” 原则：

1. 静态路由 (routes/about.tsx) 优先级最高。
2. 动态段 (routes/posts.$id.tsx) 优先级次之。
3. Catch-All (routes/$.tsx) 优先级最低，只有在前两者都匹配失败时才会被触发。

Optional Parameters

在 TanStack Router 的 file-based routing 中，{-$locale}.archive.{-$year}.{-$month}.{-$day}.tsx这种写法属于 非常典型的“多段动态路径 + 可选参数” 的文件命名方式。它通常用于实现带日期和语言的博客/文章/新闻归档路由，是非常常见的真实项目写法。

这个文件名到底匹配什么 URL？它会匹配下面这种结构的 URL：

xxxxxxxxxx
5
1
/zh/archive/2024/12/25
2
/en/archive/2025/01/01
3
/ja/archive/2023/08/15
4
/archive/2025/03/07                 ← 没有语言部分也可以（视配置）
5
/zh-hant/archive/2024/11/11

简单说就是：

xxxxxxxxxx
1
1
可选的语言前缀 / archive / 年 / 月 / 日

各部分具体含义

几种常见的实际匹配例子

为什么前面要加 -？（非常重要的细节）

TanStack Router 的动态参数有两种写法：

xxxxxxxxxx
2
1
$year.tsx         ← 普通动态参数（必须存在）
2
{-$year}.tsx      ← 可选动态参数（这一段可以不存在）

- 的作用就是让这个路径段变成可选。所以 {-$locale}.archive.{-$year}.{-$month}.{-$day}.tsx 的意思是：

前面的语言和后面的年/月/日 都可以不存在，只要中间有 /archive 就行（但实际项目里通常会搭配 loader 来做更严格的验证）

范例代码：

xxxxxxxxxx
115
1
// routes/{-$locale}.archive.{-$year}.{-$month}.{-$day}.tsx
2
​
3
import { createFileRoute } from '@tanstack/react-router'
4
import { useSuspenseQuery } from '@tanstack/react-query'
5
import { format, parse } from 'date-fns'
6
import { zhCN, enUS, ja } from 'date-fns/locale'
7
​
8
// 假设你有这样的文章数据获取函数
9
import { getPostsByDate } from '@/lib/api/posts'
10
​
11
export const Route = createFileRoute('/archive')({
12
  // 可选：定义更严格的 params 解析规则（推荐）
13
  parseParams: (params) => ({
14
    locale: params.locale || 'en', // 默认语言
15
    year: params.year ? Number(params.year) : undefined,
16
    month: params.month ? Number(params.month) : undefined,
17
    day: params.day ? Number(params.day) : undefined,
18
  }),
19
​
20
  stringifyParams: ({ locale, year, month, day }) => ({
21
    ...(locale !== 'en' && { locale }),
22
    ...(year && { year: String(year) }),
23
    ...(month && { month: String(month).padStart(2, '0') }),
24
    ...(day && { day: String(day).padStart(2, '0') }),
25
  }),
26
​
27
  // 核心数据加载逻辑
28
  loader: async ({ params, context: { queryClient } }) => {
29
    const { year, month, day, locale } = params
30
​
31
    // 根据参数决定查询范围
32
    let dateFilter:
33
      | { year: number; month?: number; day?: number }
34
      | undefined = undefined
35
​
36
    if (year) {
37
      dateFilter = { year }
38
      if (month) {
39
        dateFilter.month = month
40
        if (day) dateFilter.day = day
41
      }
42
    }
43
​
44
    return queryClient.ensureQueryData({
45
      queryKey: ['posts', 'archive', dateFilter, locale],
46
      queryFn: () => getPostsByDate(dateFilter, locale),
47
    })
48
  },
49
​
50
  // 组件
51
  component: ArchivePage,
52
})
53
​
54
// 日期格式化辅助函数
55
const getDateTitle = (params: Route['types']['Params']) => {
56
  const { year, month, day, locale } = params
57
​
58
  const locales = { 'zh-CN': zhCN, 'en': enUS, 'ja': ja }
59
  const dateLocale = locales[locale as keyof typeof locales] ?? enUS
60
​
61
  if (day && month && year) {
62
    return format(
63
      new Date(year, month - 1, day),
64
      'PPP', // e.g. Dec 25th, 2025
65
      { locale: dateLocale }
66
    )
67
  }
68
  if (month && year) {
69
    return format(new Date(year, month - 1), 'MMMM yyyy', { locale: dateLocale })
70
  }
71
  if (year) {
72
    return String(year)
73
  }
74
  return 'All Archives'
75
}
76
​
77
function ArchivePage() {
78
  const { locale = 'en', year, month, day } = Route.useParams()
79
​
80
  const { data: posts = [] } = useSuspenseQuery(
81
    Route.useQueryOptions() // 自动使用上面 loader 的 queryKey & queryFn
82
  )
83
​
84
  const title = getDateTitle({ locale, year, month, day })
85
​
86
  return (
87
    <div className="container mx-auto py-12">
88
      <h1 className="text-4xl font-bold mb-8">
89
        {title} {locale !== 'en' && `(${locale.toUpperCase()})`}
90
      </h1>
91
​
92
      {posts.length === 0 ? (
93
        <p className="text-muted-foreground">No posts found for this period.</p>
94
      ) : (
95
        <div className="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
96
          {posts.map((post) => (
97
            <article key={post.id} className="border rounded-lg p-6 hover:shadow-md transition">
98
              <time className="text-sm text-muted-foreground">
99
                {format(new Date(post.date), 'PPP')}
100
              </time>
101
              <h2 className="text-xl font-semibold mt-2">
102
                <Link to="/posts/$slug" params={{ slug: post.slug }}>
103
                  {post.title}
104
                </Link>
105
              </h2>
106
              <p className="mt-2 text-muted-foreground line-clamp-2">
107
                {post.excerpt}
108
              </p>
109
            </article>
110
          ))}
111
        </div>
112
      )}
113
    </div>
114
  )
115
}

Search Parameters

在 TanStack Router 中，Search Parameters（查询参数，即 URL 中 ? 后面的部分） 被提升到了“一等公民”的地位。

与传统的路由库不同，TanStack Router 要求你对查询参数进行显式验证和类型定义。这意味着你可以像处理组件的 Props 一样，以类型安全的方式处理 URL 参数。

1. 核心流程：验证与定义

要使用 Search Params，你必须在定义路由时使用 validateSearch 函数。

xxxxxxxxxx
18
1
// routes/users.tsx
2
import { createFileRoute } from '@tanstack/react-router'
3
​
4
// 2. 在路由中引用
5
export const Route = createFileRoute('/users')({
6
  component: UserComponent,
7
  // 验证函数：如果验证通过，返回的数据就是强类型的
8
  validateSearch: (search: Record<string, unknown>) => {
9
    return {
10
        page: (search.page as number),
11
        sort_by: (search.sort_by as string) || "",
12
    }  
13
  },
14
  // 在 Loader 中也可以直接拿到强类型的 params
15
  loader: ({ search }) => {
16
    console.log(search.page) // 这里 search.page 自动就是 number 类型
17
  }
18
})

2. 为什么这样做？（三大优势）

• 类型安全：当你使用 useSearch() 钩子时，你拿到的 page 是真正的 number 类型，而不是字符串。
• 运行时纠错：如果用户手动在地址栏输入了非法的参数（例如 ?page=abc），fallback 或验证逻辑会自动修正它，防止页面崩溃。
• Link 跳转保护：当你使用 <Link to="/users" search={{ page: 2 }} /> 时，IDE 会自动补全参数名；如果你漏写了必填参数，代码会报错。

3. 如何在代码中使用

获取参数：useSearch

xxxxxxxxxx
4
1
function UsersComponent() {
2
  const { page, filter } = Route.useSearch()
3
  return <div>当前页码：{page}</div>
4
}

修改参数：useNavigate 或 <Link>

改变 Search Params 通常用于分页、排序和搜索过滤。

xxxxxxxxxx
8
1
const navigate = useNavigate({ from: Route.fullPath })
2
​
3
// 更新参数而不丢失其他参数
4
const handlePageChange = (newPage: number) => {
5
  navigate({
6
    search: (prev) => ({ ...prev, page: newPage }),
7
  })
8
}

4. Search Params vs Path Params

5. 进阶：JSON 状态压缩

TanStack Router 支持将复杂的对象甚至数组放入 Search Params。它会自动处理序列化和反序列化，让你可以直接在 URL 中存储像 ?filters={"status":["active","pending"]} 这样的复杂状态。

例子：

xxxxxxxxxx
13
1
<Link to="/products" search={{
2
        sort_by: "price",
3
        product_type: ["shoes", "t-shirts"],
4
        pagination: {
5
            page: 1,
6
            pageSize: 10
7
        },
8
        colors: ["red", "blue"],
9
        sale: true
10
    }}
11
>
12
    Products with Filters
13
</Link>

总结

在 TanStack Router 中，Search Params 不再是“杂乱的字符串”。通过 validateSearch，你把 URL 变成了一个类型安全的全局状态管理器。

Validating Search Params with Zod

虽然可以自己写search params的校验逻辑，但是结合zod使用就非常高效。

安装依赖pnpm add @tanstack/zod-adapter。

在 TanStack Router 中使用 Zod 校验 Search Params，本质上是把 URL 字符串 变成 结构化的 TypeScript 对象。

当你访问 ?page=1&filter=react 时，浏览器只知道它们是字符串。Zod 的作用就是解析、转换并确保这些数据的安全。

一个典型的校验逻辑拆解，比如说url是这样的/search?page=1&criteria={"query":"laptop","range":{"min":1000,"max":5000}}&tags=electronics&tags=sale。

第一步：定义zod schema

xxxxxxxxxx
20
1
import { z } from 'zod'
2
​
3
const searchSchema = z.object({
4
  // 1. 基础字段
5
  page: z.coerce.number().catch(1),
6
​
7
  // 2. 嵌套对象：搜索标准
8
  criteria: z.object({
9
    query: z.string().default(''),
10
    range: z.object({
11
      min: z.number().catch(0),
12
      max: z.number().catch(99999),
13
    }).default({ min: 0, max: 99999 })
14
  }).default({ query: '', range: { min: 0, max: 99999 } }),
15
​
16
  // 3. 数组字段：多选标签
17
  tags: z.array(z.string()).catch([]),
18
});
19
​
20
type SearchParams = z.infer<typeof searchSchema>;

常见转换方法：

第二步：配置路由与 Loader

在这里，Loader 会直接拿到经过 Zod 清洗后的数据，直接发送给 API。

可以看到，validateSearch里面就很简单了。

xxxxxxxxxx
25
1
import { createFileRoute } from '@tanstack/react-router'
2
import { zodValidator } from '@tanstack/zod-adapter'
3
​
4
const searchSchema......
5
​
6
type SearchParams......
7
​
8
export const Route = createFileRoute('/_admin/products')({
9
  // 1. 验证查询参数
10
  validateSearch: zodValidator(productSearchSchema),
11
​
12
  // 2. 预加载数据：search 参数已经是强类型的了
13
  loader: ({ search }) => {
14
    // 假设这是一个从后台获取数据的函数
15
    return fetchProducts({
16
      page: search.page,
17
      q: search.filter,
18
      tags: search.categories,
19
      sort: search.sort,
20
      includeArchived: search.showArchived
21
    })
22
  },
23
  
24
  component: ProductsPage,
25
})

第三步：组件内的交互

展示如何使用 useSearch 获取状态，以及如何通过 useNavigate 修改状态。

xxxxxxxxxx
46
1
function ProductsPage() {
2
  const { page, filter, categories, sort } = Route.useSearch()
3
  const navigate = useNavigate({ from: Route.fullPath })
4
  const products = Route.useLoaderData()
5
​
6
  // 修改排序的函数
7
  const updateSort = (newSort: string) => {
8
    navigate({
9
      search: (prev) => ({ ...prev, sort: newSort as any, page: 1 }),
10
    })
11
  }
12
​
13
  // 切换分类的函数（处理数组）
14
  const toggleCategory = (cat: string) => {
15
    const nextCategories = categories.includes(cat)
16
      ? categories.filter((c) => c !== cat)
17
      : [...categories, cat]
18
      
19
    navigate({
20
      search: (prev) => ({ ...prev, categories: nextCategories, page: 1 }),
21
    })
22
  }
23
​
24
  return (
25
    <div>
26
      <h1>商品管理 ({page})</h1>
27
      
28
      {/* 搜索框 */}
29
      <input 
30
        value={filter ?? ''} 
31
        onChange={(e) => navigate({ search: (prev) => ({ ...prev, filter: e.target.value || undefined }) })}
32
      />
33
​
34
      {/* 排序下拉 */}
35
      <select value={sort} onChange={(e) => updateSort(e.target.value)}>
36
        <option value="newest">最新上架</option>
37
        <option value="price_asc">价格从低到高</option>
38
      </select>
39
​
40
      {/* 列表渲染 */}
41
      <ul>
42
        {products.map(p => <li key={p.id}>{p.name} - ${p.price}</li>)}
43
      </ul>
44
    </div>
45
  )
46
}

4. 这个“复杂”例子的核心亮点
5. 数据过滤逻辑高度一致：由于采用了 validateSearch，用户无论是在搜索框输入、点击分页、还是点击浏览器后退按钮，页面拿到的 search 对象格式永远是一致且安全的。
6. Loader 自动触发：只要 URL 里的 page 或 filter 变了，TanStack Router 就会自动重新调用 Loader 获取新数据。你不需要写任何 useEffect 来监听参数变化。
7. URL 是唯一的真理 (Single Source of Truth)：整个页面的过滤、排序状态完全由 URL 决定。你可以直接把当前的链接发给同事，他打开看到的页面和你一模一样。
8. Zod 的预处理 (preprocess)：在处理布尔值（如 showArchived）时，URL 里是字符串 "true"，Zod 自动将其转成了 JavaScript 的 true。

Zod 在路由生命周期中的位置

TanStack Router 保证了在你的组件渲染之前，数据就已经通过了 Zod 的检查。

• 输入：浏览器地址栏原始字符串 ?page=5&view=grid。
• 校验层 (validateSearch)：Zod 运行 parse()。它检查 page 是否能转成数字，view 是否在枚举里。
• 输出：一个干净的 JavaScript 对象 { page: 5, view: 'grid' }。
• 消费：你的组件通过 Route.useSearch() 直接拿到这个对象，类型提示是完美的。

Handling Search Params Errors

如果用户输入了错入的url地址，该怎么处理呢？

在 TanStack Router 中，Zod 的错误处理主要分为两个层面：Schema 内部的“自动纠错”和路由层面的“全局拦截”。

1. 第一道防线：Zod 内部的“软处理” (推荐)

这是最常用的方式，通过在 Schema 中定义“后路”，确保即使用户输入错误，应用也不会挂掉。

A. 使用 .catch() (最强纠错)

无论发生什么错误（解析失败、类型不符、为空），都返回一个指定的默认值。

xxxxxxxxxx
4
1
const schema = z.object({
2
  // 如果 URL 是 ?page=hello，page 会自动变成 1
3
  page: z.coerce.number().catch(1), 
4
})

B. 使用 .default() (处理缺失)

只在 URL 中缺少该参数时生效。

xxxxxxxxxx
4
1
const schema = z.object({
2
  // URL 没有 page 参数时为 1；如果有 page=abc，校验依然会报错
3
  page: z.coerce.number().default(1), 
4
})

C. 结合使用

通常建议这样写，既能处理缺失，也能处理错误：

xxxxxxxxxx
1
1
page: z.coerce.number().catch(1) // 只要不是数字，通通变回 1

D. 使用fallback处理

fallback 函数通常是从 @tanstack/react-router 中导出的，专门用于 validateSearch 阶段。

xxxxxxxxxx
14
1
import { fallback } from '@tanstack/react-router'
2
import { z } from 'zod'
3
​
4
export const Route = createFileRoute('/search')({
5
  validateSearch: (search) => {
6
    return {
7
      // 使用 fallback 函数
8
      query: fallback(z.string(), 'default-query').parse(search.query),
9
      
10
      // 或者在对象里配合使用
11
      page: fallback(z.number(), 1).parse(search.page),
12
    }
13
  },
14
})

fallback，catch二者选择一种就行了，千万不要混着使用，因为二者效果是一致的，混着使用代码可读性非常差。

2. 第二道防线：路由层面的“硬拦截”

如果你没有在 Zod Schema 中写 .catch()，那么当 Zod 校验失败（.parse() 抛出异常）时，TanStack Router 会启动错误流程。

A. 触发 errorComponent

如果 validateSearch 抛出错误，该路由的 errorComponent 会被渲染。你可以在这里给用户展示一个“搜索条件错误”的提示。

xxxxxxxxxx
7
1
export const Route = createFileRoute('/products')({
2
  validateSearch: zodValidator(productSearchSchema),
3
  // 当 Zod 报错时，渲染这个组件
4
  errorComponent: ({ error }) => {
5
    return <div>输入的搜索参数不对哦：{error.message}</div>
6
  },
7
})

B. 拦截重定向

你也可以在校验失败时，强行把用户踢回正确的 URL。

xxxxxxxxxx
13
1
export const Route = createFileRoute('/products')({
2
  validateSearch: (search) => {
3
    try {
4
      return productSearchSchema.parse(search)
5
    } catch (e) {
6
      // 发现错误，直接重定向到第一页
7
      throw redirect({
8
        to: '/products',
9
        search: { page: 1 },
10
      })
11
    }
12
  },
13
})

3. Zod 错误处理的底层逻辑图

1. 用户修改 URL -> 2. validateSearch 执行 -> 3. Zod 校验：

   • 成功 -> 进入 loader -> 渲染组件。
   • 失败 (有 .catch) -> 修正数据 -> 进入 loader -> 渲染组件。
   • 失败 (无 .catch) -> 抛出异常 -> 寻找最近的 errorComponent 或跳转。

4. 进阶：如何自定义 Zod 报错信息？

有时候你想在 UI 上精确显示哪个字段错了，可以利用 Zod 的 errorMap 或者简单的 try-catch。

xxxxxxxxxx
6
1
const productSearchSchema = z.object({
2
  page: z.coerce.number({
3
    invalid_type_error: "页码必须是数字",
4
    required_error: "页码不能为空"
5
  }),
6
})

5. 总结：最佳实践建议

1. 对于分页、排序、筛选：一律使用 .catch()。

   • 原因：用户手动改 URL 很正常，不应该因为一个参数错了就让整个页面崩溃（显示报错页面）。让他们回到默认状态是最好的体验。

2. 对于关键性业务参数：不使用 .catch()，让它抛错。

   • 原因：比如一个加密的校验 Token，如果错了，就应该明确显示“链接已失效”。

3. 使用 zodValidator：它会自动处理 Zod 的 ZodError 对象，并将其传递给 errorComponent，让你能拿到详细的错误数组（哪些字段错了，原因是什么）。

More on the Link Component

1. 强类型的参数检查 (Type-Safe Params & Search)

这是 TanStack Router 最核心的优势。如果你定义的路由有动态参数或查询参数，<Link> 会强制要求你提供它们，否则代码无法通过编译。

• 路径参数：如果去往 /posts/$postId，你必须传 params。
• 查询参数：如果 /users 路由有 validateSearch，你必须传 search。

xxxxxxxxxx
8
1
// 自动补全和类型检查
2
<Link 
3
  to="/posts/$postId" 
4
  params={{ postId: '123' }} 
5
  search={{ showDetails: true }}
6
>
7
  查看文章
8
</Link>

2. 智能预加载 (Intent-based Preloading)

TanStack Router 可以在用户真正点击链接之前就加载好数据（Loader）。

• preload: 'intent' (默认/推荐)：当用户鼠标悬停 (Hover) 在链接上，或者手指按住链接时，后台会立即开始执行该路由的 loader。
• preload: 'render'：只要链接出现在屏幕上，就立即预加载。

xxxxxxxxxx
7
1
<Link 
2
  to="/dashboard" 
3
  preload="intent" 
4
  preloadDelay={50} // 悬停 50ms 后触发
5
>
6
  后台管理
7
</Link>

效果：用户点击时，数据通常已经加载好了，页面秒开。

3. 函数式更新 Search Params

当你只想修改当前 URL 的一个查询参数（例如分页），而不影响其他参数时，可以使用函数写法。这避免了手动合并复杂的 search 对象。

xxxxxxxxxx
16
1
<Link
2
  // 1. 明确告诉 Link，我从当前路由“这里”出发
3
  from={Route.fullPath}
4
    
5
  // 2. 不写 to，意味着目标就是“这里”
6
    
7
  // 3. 这里的 prev 就会被正确推导为当前路由的 Search Params 类型
8
  search={(prev) => ({ 
9
        ...prev, 
10
        pagination: {
11
            ...prev.pagination,
12
            page: (prev.pagination?.page || 1) + 1,
13
    } })} // 仅修改 page
14
>
15
  下一页
16
</Link>

4. 动态 Active 状态处理

你可以根据链接是否处于激活状态（Active）来应用不同的样式或组件。

• activeProps：激活时的样式属性。
• inactiveProps：未激活时的样式属性。
• children 函数：根据激活状态渲染不同的内容。

xxxxxxxxxx
11
1
<Link
2
  to="/settings"
3
  activeProps={{ className: 'font-bold text-blue-600' }}
4
  inactiveProps={{ className: 'text-gray-500' }}
5
>
6
  {({ isActive }) => (
7
    <>
8
      设置 {isActive && <StarIcon />}
9
    </>
10
  )}
11
</Link>

5. Data 属性与 View Transitions

你可以配合浏览器原生的 View Transitions API 实现平滑的页面过渡效果。

xxxxxxxxxx
6
1
<Link
2
  to="/profile"
3
  viewTransition // 开启视图过渡动画
4
>
5
  个人主页
6
</Link>

6. 遮罩跳转 (Masking URL)

有时候你想让用户跳转到某个路由，但在地址栏显示另一个更美观的地址。

xxxxxxxxxx
7
1
<Link
2
  to="/photos/$photoId"
3
  params={{ photoId: '5' }}
4
  mask={{ to: '/photos/view' }} // 实际上地址栏会显示 /photos/view
5
>
6
  查看图片
7
</Link>

总结：Link 的高级特性对比

如果我使用了tanstack/router，也使用了tanstack/table，我该怎么处理分页和搜索呢？

将 Table 的状态（分页、排序、过滤）“同步”到 URL 中。url长度是有限的，只要不超过这个限制，就没有问题。

不要在表格组件里使用 useState 来维护 pageIndex 或 globalFilter，而是：

1. 从 URL 读取状态（通过 useSearch）。
2. 将状态传给 Table（作为 state 属性）。
3. 在 Table 变化时更新 URL（通过 onStateChange 触发 Maps）。

Other ways to Navigate Programmatically

1. 使用 useNavigate Hook (最常用)

这是在组件内部进行逻辑跳转的标准方式。它返回一个 Maps 函数，支持与 <Link> 完全相同的类型安全参数。

xxxxxxxxxx
13
1
import { useNavigate } from '@tanstack/react-router'
2
​
3
function LoginButton() {
4
  const navigate = useNavigate()
5
​
6
  const handleLogin = async () => {
7
    await auth.login()
8
    // 逻辑执行完后跳转
9
    navigate({ to: '/dashboard' })
10
  }
11
​
12
  return <button onClick={handleLogin}>登录</button>
13
}

高级技巧： 配合 from 属性，你可以像 Link 一样实现 Search Params 的函数式更新。因为from属性指定之后，tanstack会记住当前路由的参数。

xxxxxxxxxx
6
1
const navigate = useNavigate({ from: '/products' })
2
​
3
// 仅更新分页，不写 to
4
navigate({
5
  search: (prev) => ({ ...prev, page: prev.page + 1 })
6
})

2. 在 Loader 或 BeforeLoad 中使用 throw redirect

如果你需要在页面渲染 之前 进行拦截并跳转（例如：未登录用户访问后台），你应该使用 redirect 函数。

• 特点：必须使用 throw 关键字，这会中断当前的路由解析流程并立即跳转。

xxxxxxxxxx
10
1
export const Route = createFileRoute('/admin')({
2
  beforeLoad: ({ search }) => {
3
    if (!isAuthenticated()) {
4
      throw redirect({
5
        to: '/login',
6
        search: { redirect: '/admin' }, // 记录来源以便登录后跳回
7
      })
8
    }
9
  },
10
})

3. 使用 router.navigate (全局 API)

如果你在组件外部（例如在 Redux 中、全局拦截器中或普通 JS 函数里），可以通过直接访问 router 实例来进行跳转。

xxxxxxxxxx
6
1
import { router } from '../main' // 假设你导出了创建的 router 实例
2
​
3
export function logout() {
4
  localStorage.removeItem('token')
5
  router.navigate({ to: '/login' })
6
}

4. 路由跳转方式对比

5. 跳转时的“姿势”控制

在调用跳转方法时，你可以通过一些特殊的属性来控制跳转行为：

• replace: true：使用 history.replaceState 而不是 pushState。这不会在浏览器历史记录中留下新条目，常用于搜索过滤。
• resetScroll: false：跳转后保留滚动位置（默认通常是滚动到顶部）。
• state：可以传递一些临时的、不显示在 URL 里的状态（通过 location.state 获取）。

其实还有一个<Navigate to="">组件可以用来跳转，但是这个组件有一个问题，它是当组件被渲染时，立即触发路由跳转。可能会造成页面闪动、白屏的情况，使用时需注意。

Context

在 TanStack Router 中，Context（上下文） 是一个非常强大的特性，它允许你在路由树中自上而下地传递数据、服务或状态（例如：QueryClient、Auth 信息、主题等）。

1. 核心流程：从根路由开始

Context 的传递通常是从 rootRoute 开始定义的。

第一步：定义 Context 类型

首先，你需要定义一个类型来描述你的上下文包含什么。

xxxxxxxxxx
13
1
// src/routes/__root.tsx
2
​
3
interface MyRouterContext {
4
  auth: {
5
    isAuthenticated: boolean
6
    user: User | null
7
  }
8
}
9
​
10
// 创建 rootRoute 时传入类型
11
export const Route = createRootRouteWithContext<MyRouterContext>()({
12
  component: RootComponent,
13
})

第二步：在创建 Router 时注入具体值

在你的 main.tsx 或 App.tsx 中，你需要把真实的数据传给 createRouter。

xxxxxxxxxx
10
1
const router = createRouter({
2
  routeTree,
3
  context: {
4
    // 这里的初值通常是占位符，或者在初始化时确定的值
5
    auth: {
6
      isAuthenticated: false,
7
      user: null,
8
    }, 
9
  },
10
})

2. 在子路由中消费 Context

子路由可以通过 beforeLoad 或 loader 访问到这些 Context。

xxxxxxxxxx
13
1
export const Route = createFileRoute('/dashboard')({
2
  // context 包含从父级（如 root）传下来的所有内容
3
  loader: ({ context }) => {
4
    // 甚至可以在这里直接使用注入的 queryClient 请求数据
5
    return context.queryClient.ensureQueryData(productsQueryOptions)
6
  },
7
  beforeLoad: ({ context }) => {
8
    // 权限检查逻辑
9
    if (!context.auth.isAuthenticated) {
10
      throw redirect({ to: '/login' })
11
    }
12
  },
13
})

3. Context 的“继承与合并”

Context 是可以累加的。父路由可以向下传递 Context，子路由也可以在自己的 beforeLoad 中添加新的 Context 给它的子路由。

• Root Route: 提供 queryClient。
• _auth Layout Route: 在 beforeLoad 中获取 user 详情，并将其加入 Context。
• _auth.profile Route: 此时的 Context 既包含 queryClient 也包含 user。

xxxxxxxxxx
10
1
// _auth.tsx (布局路由)
2
export const Route = createFileRoute('/_auth')({
3
  beforeLoad: async ({ context }) => {
4
    const user = await fetchUser()
5
    return {
6
      // 返回的对象会合并到当前及子路由的 context 中
7
      user, 
8
    }
9
  },
10
})

4. 在组件中获取 Context

如果你需要在 UI 组件中访问 Context，可以使用 useContext 钩子（注意：这是 Route 对象自带的钩子）。

xxxxxxxxxx
6
1
function ProfileComponent() {
2
  // 拿到的是整个路由树合并后的完整 Context
3
  const context = Route.useRouteContext()
4
  
5
  return <div>你好, {context.user.name}</div>
6
}

5. 常见实战场景：集成 TanStack Query

这是 Context 最常见的用法。通过将 queryClient 注入 Context，你可以在所有路由的 loader 中预取数据。

TypeScript

xxxxxxxxxx
4
1
export const Route = createFileRoute('/posts/$postId')({
2
  loader: ({ context: { queryClient }, params: { postId } }) => 
3
    queryClient.ensureQueryData(postQueryOptions(postId))
4
})

6. 为什么不用 React Context？

虽然它们名字一样，但 Router Context 有几个独特的优势：

1. 非渲染时机访问：React Context 只能在组件渲染时（Hooks）使用，而 Router Context 可以在路由跳转前（loader / beforeLoad）使用。
2. 类型安全：通过 createRootRouteWithContext，整个路由树的 Context 都是强类型的，IDE 会全程提供补全。
3. 数据流清晰：它迫使你思考哪些数据是路由级别的（权限、数据客户端），哪些是 UI 级别的。